Skip to content

Conversation

@vbotbuildovich
Copy link
Contributor

@vbotbuildovich vbotbuildovich commented Dec 20, 2025

This PR adds the latest OpenAPI spec for version v25.3.4 of the Redpanda Admin API:

npx doc-tools generate bundle-openapi --tag v25.3.4 --use-admin-major-version --surface admin --out-admin admin/admin-v2.yaml

@vbotbuildovich vbotbuildovich requested a review from a team as a code owner December 20, 2025 17:39
@coderabbitai
Copy link

coderabbitai bot commented Dec 20, 2025

📝 Walkthrough

Walkthrough

The pull request updates the OpenAPI specification file admin/admin-v2.yaml with metadata and documentation improvements. The changes include bumping the x-redpanda-core-version from v25.3.2 to v25.3.3, updating the x-generated-at timestamp, and revising path operation descriptions and summaries across several endpoints (GetBroker, ListBrokers, ListKafkaConnections, ShadowLink operations). No changes are made to request/response schemas, endpoints, or the API surface.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

  • Single file with metadata and documentation-only updates
  • No functional, structural, or schema changes to verify
  • Descriptions are straightforward and can be quickly scanned for accuracy and clarity

Possibly related PRs

  • redpanda-data/api-docs#29: Introduces the initial full v2 OpenAPI spec file, which this PR now updates with refined metadata and operation descriptions.

Suggested reviewers

  • kbatuigas
  • paulohtb6

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check ✅ Passed The PR title accurately describes the main change: updating Admin API docs for a specific version (v25.3.4). It is clear, concise, and directly relates to the changeset.
Description check ✅ Passed The description is related to the changeset, explaining the command used to generate the updated OpenAPI spec and specifying the version being added (v25.3.4).
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch auto-docs/admin-api

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/admin (branch: v1) API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/admin (branch: v2) API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/http-proxy API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/schema-registry API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/cloud-dataplane API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@github-actions
Copy link

github-actions bot commented Dec 20, 2025

ℹ️ Redpanda/cloud-controlplane API content change detected

Preview documentation

No structural change, nothing to display.

Powered by Bump.sh

@vbotbuildovich vbotbuildovich changed the title auto-docs: Update Admin API docs for v25.3.3 auto-docs: Update Admin API docs for v25.3.4 Dec 26, 2025
$ref: "#/components/schemas/connect.error"
description: Error
summary: ListKafkaConnections
summary: ListKafkaConnections returns information about the cluster's Kafka connections, collected and ordered across all brokers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: ListKafkaConnections returns information about the cluster's Kafka connections, collected and ordered across all brokers.
summary: ListKafkaConnections returns information about the cluster's Kafka connections, collected and ordered across all brokers.

/redpanda.core.admin.v2.ShadowLinkService/FailOver:
post:
description: Fails over a shadow link or a single shadow topic for disaster recovery.
description: Fails over a shadow link or a single shadow topic
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Fails over a shadow link or a single shadow topic
description: Fails over a shadow link or a single shadow topic.

Returns information about a shadow topic on a shadow link.
A shadow topic is a resource created automatically by a shadow link. The
shadow topic 'shadows' a topic on a source cluster, mirroring the data
This operation returns information about a Shadow Topic on a Shadow Link.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our DR docs do not use this capitalization style. The enterprise feature is Shadowing. Docs use shadow linking, and shadow topics.

$ref: "#/components/schemas/connect.error"
description: Error
summary: GetShadowTopic
summary: This operation returns information about a Shadow Topic on a Shadow Link. A Shadow Topic is a resource created automatically by a Shadow Link. The Shadow Topic 'shadows' a topic on a source cluster, mirroring the data and properties of that topic.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment re capitalization

description: |-
Returns a list of all shadow topics on a shadow link and
their status.
This operation returns a list of all Shadow Topics on a Shadow Link and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This operation returns a list of all Shadow Topics on a Shadow Link and
This operation returns a list of all shadow topics on a shadow link and

$ref: "#/components/schemas/connect.error"
description: Error
summary: ListShadowTopics
summary: This operation returns a list of all Shadow Topics on a Shadow Link and their status
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
summary: This operation returns a list of all Shadow Topics on a Shadow Link and their status
summary: This operation returns a list of all shadow topics on a shadow link and their status

@kbatuigas
Copy link
Contributor

kbatuigas commented Jan 14, 2026

Using a specific tagged release (--tag v25.3.4) with the generate command results in the generated spec not including the changes introduced in redpanda-data/redpanda#29040.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants